Shadow Door User's Manual

Copyright 2003 by Robert Zubek and Phillip Saltzman, Northwestern University
shadow-door-dev@cs.northwestern.edu

Under the Hood

Here come the nasty architectural bits. :)

Use of Shadow Door is a matter of three different parts playing together: an external process that sends commands and receives observations through a socket using the Shadow Door Protocol, a server extension that translates between the socket and the ongoing game, and a set of NWN scripts that execute commands and send back observations.

When you run NWNX2 with Shadow Door, it starts up a new game server, but also opens a socket on port 1890 and listens for incoming commands. The diagram is roughly as follows:

Process #1 External AI controller (Lisp, etc.)
| | | | | |	Shadow Door Protocol over TCP on port 1890
Process #2 NWServer + NWNX 2.5 + Shadow Door
| | | | | |	BioWare's Propertiary Protocol
Process #3 Neverwinter Nights Graphical Client

Shadow Door Protocol

The AI sends the NPC commands through the socket interface, and the NPC sends back observations. They are both serialized 8-bit ASCII strings with one or more tokens separated by # signs, and terminated with a CR, for example: "speak!#waves#hi rob" or "attacked-by#rob". The more general syntax is:

" <command-or-observation>[#[<parameter>]]+<LF>"

with a grammar as follows:

command := head body terminator
head := token
body := parameter body | parameter
parameter := separator token | separator
separator := '#' (ASCII character #35, 0x23)
token := tokenchar+
tokenchar := any ASCII character except for CR (0x0D), LF (0x0A) or # (0x23)
terminator := LF  (ASCII character #10, 0x0A)

Omitted parameters are allowed; they are equivalent to an empty string. Currently supported commands are:

• speak! with parameters emote and text
  Example: "speak!#smiles#hi there" will result in the NPC uttering " *smiles* hi there " in text floating above it.
  
• animate! with parameters animation-type ,  speed and duration-in-secods
  Example: "animate!#4#1.0#4.0" or "animate!#107#0.8#"
  See the Lisp sources (or NWScript sources) for numeric values of different animations
  
• attack! with parameter victim-name
  Example: "attack!#rob"
  
• moveto! with parameter target-name
  Example: "moveto!#chest1"

Currently supported observations are:

• speech with parameters name, emote and text
  Example: "speech#rob##hi eliza"
  
• attacked-by with parameter attacker
  Example: "attacked-by#rob"